<html>
<head>
<title>GFT - Google Fusion Tables</title>
</head>

<body bgcolor="#ffffff">

<h1>GFT - Google Fusion Tables</h1>

(GDAL/OGR >= 1.9.0)<p>

This driver can connect to the Google Fusion Tables service. GDAL/OGR must be built with Curl support in order to the
GFT driver to be compiled.<p>

The driver supports read and write operations.<p>

<h2>Dataset name syntax</h2>

The minimal syntax to open a GFT datasource is : <pre>GFT:</pre><p>

Additionnal optional parameters can be specified after the ':' sign such as :<p>

<ul>
<li> <b>tables=table_id1[,table_id2]*</b>: A list of table IDs. This is necessary when you need to access to public tables for example.
If you want the table ID of a public table, or any other table that is not owned by the authenticated user, you have to visit the table
in the Google Fusion Tables website and note the number at the end of the URL.
<li> <b>protocol=https</b>: To use HTTPS protocol for all operations. By default, HTTP is used, except for the authentication operation
where HTTPS is always used.
<li> <b>auth=auth_key</b>: An authentication key as described below.
<li> <b>access=access_token</b>: An access token as described below.
<li> <b>refresh=refresh_token</b>: A refresh token as described below.
</ul>

If several parameters are specified, they must be separated by a space.

<h2>Authentication</h2>

Most operations, in particular write operations, require a valid Google
account to provide authentication information to the driver. The only
exception is read-only access to public tables.<p>

In order to create an authorization key, it is necessary to
<a href="https://www.google.com/url?q=https%3A%2F%2Faccounts.google.com%2Fo%2Foauth2%2Fauth%3Fscope%3Dhttps%253A%252F%252Fwww.googleapis.com%252Fauth%252Ffusiontables%26state%3D%252Fprofile%26redirect_uri%3Durn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob%26response_type%3Dcode%26client_id%3D265656308688.apps.googleusercontent.com">
login and authorize</a> access to fusion tables for a Google (i.e. GMail)
account.  The resulting authorization key can be turned into a refresh
token for use OGR using the gdal/swig/python/scripts/gdal_auth.py script
distributed with GDAL (available in GDAL/OGR >= 1.10.0).  Note that auth
tokens can only be used once, while the resulting refresh token lasts
indefinitely.<p>

<pre>
  gdal_auth.py auth2refresh <i>auth_token</i>
</pre>

This refresh token can then be either set as a configuration option
(GFT_REFRESH_TOKEN) or included in the connection string
(i.e. GFT:refresh=<i>refresh_token</i>). <p>

Generally OAuth2 credentials can be provided via these mechanisms:<p>

<ul>
<li> Specifying an <i>access token</i> via the <tt>GFT_ACCESS_TOKEN</tt>
configuration/environment variable.<p>
<li> Specifying an <i>access token</i> via the <tt>access=</tt>
clause in the GFT: connection string.
<li> Specifying a <i>refresh token</i> via the <tt>GFT_REFRESH_TOKEN</tt>
configuration/environment variable.<p>
<li> Specifying an <i>refresh token</i> via the <tt>refresh=</tt>
clause in the GFT: connection string.
<li> Specifying a <i>auth key</i> via the <tt>GFT_AUTH</tt>
configuration/environment variable.<p>
<li> Specifying an <i>auth key</i> via the <tt>auth=</tt>
clause in the GFT: connection string.
</ul>

<h2>Geometry</h2>

Geometries in GFT tables must be expressed in the geodetic WGS84 SRS. GFT allows them to be encoded in different forms :
<ul>
<li>A single column with a "lat lon" or "lat,lon" string, where lat et lon are expressed in decimal degrees.</li>
<li>A single column with a KML string that is the representation of a Point, a LineString or a Polygon.</li>
<li>Two columns, one with the latitude and the other one with the longitude, both values expressed in decimal degrees.</li>
<li>A single column with an address known by the geocoding service of Google Maps.</li>
</ul>

Only the first 3 types are supported by OGR, not the last one.<p>

Fusion tables can have multiple geometry columns per table. By default, OGR
will use the first geometry column it finds. It is possible to select another
column as the geometry column by specifying <i>table_name(geometry_column_name)</i>
as the layer name passed to GetLayerByName().<p>

<h2>Filtering</h2>

The driver will forward any spatial filter set with SetSpatialFilter() to the server. It also makes the same for attribute
filters set with SetAttributeFilter().<p>

<h2>Paging</h2>

Features are retrieved from the server by chunks of 500 by default. This number can be altered with the GFT_PAGE_SIZE
configuration option.<p>

<h2>Write support</h2>

Table creation and deletion is possible. Note that fields can only be added to a table in which there are no features created yet.<p>

Write support is only enabled when the datasource is opened in update mode.<p>

The mapping between the operations of the GFT service and the OGR concepts is the following :
<ul>
<li>OGRFeature::CreateFeature() &lt;==&gt; INSERT operation</li>
<li>OGRFeature::SetFeature() &lt;==&gt; UPDATE operation</li>
<li>OGRFeature::DeleteFeature() &lt;==&gt; DELETE operation</li>
<li>OGRDataSource::CreateLayer() &lt;==&gt; CREATE TABLE operation</li>
<li>OGRDataSource::DeleteLayer() &lt;==&gt; DROP TABLE operation</li>
</ul>

When inserting a new feature with CreateFeature(), and if the command is successful, OGR will fetch the
returned rowid and use it as the OGR FID. OGR will also automatically reproject its geometry into the
geodetic WGS84 SRS if needed (provided that the original SRS is attached to the geometry).<p>

<h2>Write support and OGR transactions</h2>

The above operations are by default issued to the server synchronously with the OGR API call. This however
can cause performance penalties when issuing a lot of commands due to many client/server exchanges.<p>

It is possible to surround the CreateFeature() operation between
OGRLayer::StartTransaction() and OGRLayer::CommitTransaction().  The
operations will be stored into memory and only executed at the time
CommitTransaction() is called. Note that the GFT service only supports
up to 500 INSERTs and up to 1MB of content per transaction.<p>

Note : only CreateFeature() makes use of OGR transaction mechanism. SetFeature() and DeleteFeature()
will still be issued immediately.<p>

<h2>SQL</h2>

SQL commands provided to the OGRDataSource::ExecuteSQL() call are executed on the server side, unless the OGRSQL
dialect is specified. The subset of SQL supported by the GFT service is described in the links at the end of this page.<p>

The SQL supported by the server understands only native table id, and
not the table names returned by OGR.  For convenience, OGR will
"patch" your SQL command to replace the table name by the table id
however.<p>

<h2>Examples</h2>

<li>
Listing the tables and views owned by the authenticated user:
<pre>
ogrinfo -ro "GFT:email=john.doe@example.com password=secret_password"
</pre>
<p>

<li>
Creating and populating a table from a shapefile:
<pre>
ogr2ogr -f GFT "GFT:email=john.doe@example.com password=secret_password" shapefile.shp
</pre>
<p>

<li>
Displaying the content of a public table with a spatial and attribute filters:
<pre>
ogrinfo -ro "GFT:tables=224453" -al -spat 67 31.5 67.5 32 -where "'Attack on' = 'ENEMY'"
</pre>
<p>

<li>
Getting the auth key:
<pre>
ogrinfo --config CPL_DEBUG ON "GFT:email=john.doe@example.com password=secret_password"
</pre>

returns:
<pre>
HTTP: Fetch(https://www.google.com/accounts/ClientLogin)
HTTP: These HTTP headers were set: Content-Type: application/x-www-form-urlencoded
GFT: Auth key : A_HUGE_STRING_WITH_ALPHANUMERIC_AND_SPECIAL_CHARACTERS
</pre>

Now, you can set the GFT_AUTH environment variable to that value and simply use "GFT:" as the DSN.

<h2>See Also</h2>

<ul>
<li> <a href="http://code.google.com/intl/fr/apis/fusiontables/docs/developers_guide.html">Google Fusion Tables Developer's Guide</a><p>
<li> <a href="http://code.google.com/intl/fr/apis/fusiontables/docs/developers_reference.html">Google Fusion Tables Developer's Reference</a><p>
</ul>

</body>
</html>
